   Guile Reference Manual Copyright (C) 1996 Free Software Foundation
Copyright (C) 1997 Free Software Foundation
Copyright (C) 2000 Free Software Foundation
Copyright (C) 2001 Free Software Foundation

   Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.

   Permission is granted to copy and distribute modified versions of
this manual under the conditions for verbatim copying, provided that
the entire resulting derived work is distributed under the terms of a
permission notice identical to this one.

   Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions, except that this permission notice may be stated in a
translation approved by the Free Software Foundation.

Removing Alist Entries
......................

   To remove the element from an association list whose key matches a
specified key, use `assq-remove!', `assv-remove!' or `assoc-remove!'
(depending, as usual, on the level of equality required between the key
that you specify and the keys in the association list).

   As with `assq-set!' and friends, the specified alist may or may not
be modified destructively, and the only safe way to update a variable
containing the alist is to `set!' it to the value that `assq-remove!'
and friends return.

     address-list
     =>
     (("bob" . "11 Newington Avenue") ("mary" . "34 Elm Road")
      ("james" . "1a London Road"))

     (set! address-list (assoc-remove! address-list "mary"))
     address-list
     =>
     (("bob" . "11 Newington Avenue") ("james" . "1a London Road"))

   Note that, when `assq/v/oc-remove!' is used to modify an association
list that has been constructed only using the corresponding
`assq/v/oc-set!', there can be at most one matching entry in the alist,
so the question of multiple entries being removed in one go does not
arise.  If `assq/v/oc-remove!' is applied to an association list that
has been constructed using `acons', or an `assq/v/oc-set!' with a
different level of equality, or any mixture of these, it removes only
the first matching entry from the alist, even if the alist might
contain further matching entries.  For example:

     (define address-list '())
     (set! address-list (assq-set! address-list "mary" "11 Elm Street"))
     (set! address-list (assq-set! address-list "mary" "57 Pine Drive"))
     address-list
     =>
     (("mary" . "57 Pine Drive") ("mary" . "11 Elm Street"))

     (set! address-list (assoc-remove! address-list "mary"))
     address-list
     =>
     (("mary" . "11 Elm Street"))

   In this example, the two instances of the string "mary" are not the
same when compared using `eq?', so the two `assq-set!' calls add two
distinct entries to `address-list'.  When compared using `equal?', both
"mary"s in `address-list' are the same as the "mary" in the
`assoc-remove!' call, but `assoc-remove!' stops after removing the
first matching entry that it finds, and so one of the "mary" entries is
left in place.

 - primitive: assq-remove! alist key
 - primitive: assv-remove! alist key
 - primitive: assoc-remove! alist key
     Delete the first entry in ALIST associated with KEY, and return
     the resulting alist.

Sloppy Alist Functions
......................

   `sloppy-assq', `sloppy-assv' and `sloppy-assoc' behave like the
corresponding non-`sloppy-' procedures, except that they return `#f'
when the specified association list is not well-formed, where the
non-`sloppy-' versions would signal an error.

   Specifically, there are two conditions for which the non-`sloppy-'
procedures signal an error, which the `sloppy-' procedures handle
instead by returning `#f'.  Firstly, if the specified alist as a whole
is not a proper list:

     (assoc "mary" '((1 . 2) ("key" . "door") . "open sesame"))
     =>
     ERROR: In procedure assoc in expression (assoc "mary" (quote #)):
     ERROR: Wrong type argument in position 2 (expecting NULLP): "open sesame"
     ABORT: (wrong-type-arg)

     (sloppy-assoc "mary" '((1 . 2) ("key" . "door") . "open sesame"))
     =>
     #f

Secondly, if one of the entries in the specified alist is not a pair:

     (assoc 2 '((1 . 1) 2 (3 . 9)))
     =>
     ERROR: In procedure assoc in expression (assoc 2 (quote #)):
     ERROR: Wrong type argument in position 2 (expecting CONSP): 2
     ABORT: (wrong-type-arg)

     (sloppy-assoc 2 '((1 . 1) 2 (3 . 9)))
     =>
     #f

   Unless you are explicitly working with badly formed association
lists, it is much safer to use the non-`sloppy-' procedures, because
they help to highlight coding and data errors that the `sloppy-'
versions would silently cover up.

 - primitive: sloppy-assq key alist
     Behaves like `assq' but does not do any error checking.
     Recommended only for use in Guile internals.

 - primitive: sloppy-assv key alist
     Behaves like `assv' but does not do any error checking.
     Recommended only for use in Guile internals.

 - primitive: sloppy-assoc key alist
     Behaves like `assoc' but does not do any error checking.
     Recommended only for use in Guile internals.

Alist Example
.............

   Here is a longer example of how alists may be used in practice.

     (define capitals '(("New York" . "Albany")
                        ("Oregon"   . "Salem")
                        ("Florida"  . "Miami")))

     ;; What's the capital of Oregon?
     (assoc "Oregon" capitals)       => ("Oregon" . "Salem")
     (assoc-ref capitals "Oregon")   => "Salem"

     ;; We left out South Dakota.
     (set! capitals
           (assoc-set! capitals "South Dakota" "Bismarck"))
     capitals
     => (("South Dakota" . "Bismarck")
         ("New York" . "Albany")
         ("Oregon" . "Salem")
         ("Florida" . "Miami"))

     ;; And we got Florida wrong.
     (set! capitals
           (assoc-set! capitals "Florida" "Tallahassee"))
     capitals
     => (("South Dakota" . "Bismarck")
         ("New York" . "Albany")
         ("Oregon" . "Salem")
         ("Florida" . "Tallahassee"))

     ;; After Oregon secedes, we can remove it.
     (set! capitals
           (assoc-remove! capitals "Oregon"))
     capitals
     => (("South Dakota" . "Bismarck")
         ("New York" . "Albany")
         ("Florida" . "Tallahassee"))

Hash Tables
-----------

   Hash tables are dictionaries which offer similar functionality as
association lists: They provide a mapping from keys to values.  The
difference is that association lists need time linear in the size of
elements when searching for entries, whereas hash tables can normally
search in constant time.  The drawback is that hash tables require a
little bit more memory, and that you can not use the normal list
procedures (see Lists) for working with them.

Hash Table Examples
...................

   For demonstration purposes, this section gives a few usage examples
of some hash table procedures, together with some explanation what they
do.

   First we start by creating a new hash table with 31 slots, and
populate it with two key/value pairs.

     (define h (make-hash-table 31))

     (hashq-create-handle! h 'foo "bar")
     =>
     (foo . "bar")

     (hashq-create-handle! h 'braz "zonk")
     =>
     (braz . "zonk")

     (hashq-create-handle! h 'frob #f)
     =>
     (frob . #f)

   You can get the value for a given key with the procedure
`hashq-ref', but the problem with this procedure is that you cannot
reliably determine whether a key does exists in the table.  The reason
is that the procedure returns `#f' if the key is not in the table, but
it will return the same value if the key is in the table and just
happens to have the value `#f', as you can see in the following
examples.

     (hashq-ref h 'foo)
     =>
     "bar"

     (hashq-ref h 'frob)
     =>
     #f

     (hashq-ref h 'not-there)
     =>
     #f

   Better is to use the procedure `hashq-get-handle', which makes a
distinction between the two cases.  Just like `assq', this procedure
returns a key/value-pair on success, and `#f' if the key is not found.

     (hashq-get-handle h 'foo)
     =>
     (foo . "bar")

     (hashq-get-handle h 'not-there)
     =>
     #f

   There is no procedure for calculating the number of key/value-pairs
in a hash table, but `hash-fold' can be used for doing exactly that.

     (hash-fold (lambda (key value seed) (+ 1 seed)) 0 h)
     =>
     3

Hash Table Reference
....................

   Like the association list functions, the hash table functions come
in several varieties: `hashq', `hashv', and `hash'.  The `hashq'
functions use `eq?' to determine whether two keys match.  The `hashv'
functions use `eqv?', and the `hash' functions use `equal?'.

   In each of the functions that follow, the TABLE argument must be a
vector.  The KEY and VALUE arguments may be any Scheme object.

 - procedure: make-hash-table size
     Create a new hash table of SIZE slots.  Note that the number of
     slots does not limit the size of the table, it just tells how large
     the underlying vector will be.  The SIZE should be similar to the
     expected number of elements which will be added to the table, but
     they need not match.  For good performance, it might be a good
     idea to use a prime number as the SIZE.

 - primitive: hashq-ref table key [dflt]
     Look up KEY in the hash table TABLE, and return the value (if any)
     associated with it.  If KEY is not found, return DEFAULT (or `#f'
     if no DEFAULT argument is supplied).  Uses `eq?' for equality
     testing.

 - primitive: hashv-ref table key [dflt]
     Look up KEY in the hash table TABLE, and return the value (if any)
     associated with it.  If KEY is not found, return DEFAULT (or `#f'
     if no DEFAULT argument is supplied).  Uses `eqv?' for equality
     testing.

 - primitive: hash-ref table key [dflt]
     Look up KEY in the hash table TABLE, and return the value (if any)
     associated with it.  If KEY is not found, return DEFAULT (or `#f'
     if no DEFAULT argument is supplied).  Uses `equal?' for equality
     testing.

 - primitive: hashq-set! table key val
     Find the entry in TABLE associated with KEY, and store VALUE
     there. Uses `eq?' for equality testing.

 - primitive: hashv-set! table key val
     Find the entry in TABLE associated with KEY, and store VALUE
     there. Uses `eqv?' for equality testing.

 - primitive: hash-set! table key val
     Find the entry in TABLE associated with KEY, and store VALUE
     there. Uses `equal?' for equality testing.

 - primitive: hashq-remove! table key
     Remove KEY (and any value associated with it) from TABLE.  Uses
     `eq?' for equality tests.

 - primitive: hashv-remove! table key
     Remove KEY (and any value associated with it) from TABLE.  Uses
     `eqv?' for equality tests.

 - primitive: hash-remove! table key
     Remove KEY (and any value associated with it) from TABLE.  Uses
     `equal?' for equality tests.

   The standard hash table functions may be too limited for some
applications.  For example, you may want a hash table to store strings
in a case-insensitive manner, so that references to keys named
"foobar", "FOOBAR" and "FooBaR" will all yield the same item.  Guile
provides you with "extended" hash tables that permit you to specify a
hash function and associator function of your choosing.  The functions
described in the rest of this section can be used to implement such
custom hash table structures.

   If you are unfamiliar with the inner workings of hash tables, then
this facility will probably be a little too abstract for you to use
comfortably.  If you are interested in learning more, see an
introductory textbook on data structures or algorithms for an
explanation of how hash tables are implemented.

 - primitive: hashq key size
     Determine a hash value for KEY that is suitable for lookups in a
     hashtable of size SIZE, where `eq?' is used as the equality
     predicate.  The function returns an integer in the range 0 to SIZE
     - 1.  Note that `hashq' may use internal addresses.  Thus two
     calls to hashq where the keys are `eq?' are not guaranteed to
     deliver the same value if the key object gets garbage collected in
     between.  This can happen, for example with symbols: `(hashq 'foo
     n) (gc) (hashq 'foo n)' may produce two different values, since
     `foo' will be garbage collected.

 - primitive: hashv key size
     Determine a hash value for KEY that is suitable for lookups in a
     hashtable of size SIZE, where `eqv?' is used as the equality
     predicate.  The function returns an integer in the range 0 to SIZE
     - 1.  Note that `(hashv key)' may use internal addresses.  Thus
     two calls to hashv where the keys are `eqv?' are not guaranteed to
     deliver the same value if the key object gets garbage collected in
     between.  This can happen, for example with symbols: `(hashv 'foo
     n) (gc) (hashv 'foo n)' may produce two different values, since
     `foo' will be garbage collected.

 - primitive: hash key size
     Determine a hash value for KEY that is suitable for lookups in a
     hashtable of size SIZE, where `equal?' is used as the equality
     predicate.  The function returns an integer in the range 0 to SIZE
     - 1.

 - primitive: hashx-ref hash assoc table key [dflt]
     This behaves the same way as the corresponding `ref' function, but
     uses HASH as a hash function and ASSOC to compare keys.  `hash'
     must be a function that takes two arguments, a key to be hashed
     and a table size.  `assoc' must be an associator function, like
     `assoc', `assq' or `assv'.

     By way of illustration, `hashq-ref table key' is equivalent to
     `hashx-ref hashq assq table key'.

 - primitive: hashx-set! hash assoc table key val
     This behaves the same way as the corresponding `set!' function,
     but uses HASH as a hash function and ASSOC to compare keys.
     `hash' must be a function that takes two arguments, a key to be
     hashed and a table size.  `assoc' must be an associator function,
     like `assoc', `assq' or `assv'.

     By way of illustration, `hashq-set! table key' is equivalent to
     `hashx-set!  hashq assq table key'.

 - primitive: hashq-get-handle table key
     This procedure returns the `(key . value)' pair from the hash
     table TABLE.  If TABLE does not hold an associated value for KEY,
     `#f' is returned.  Uses `eq?' for equality testing.

 - primitive: hashv-get-handle table key
     This procedure returns the `(key . value)' pair from the hash
     table TABLE.  If TABLE does not hold an associated value for KEY,
     `#f' is returned.  Uses `eqv?' for equality testing.

 - primitive: hash-get-handle table key
     This procedure returns the `(key . value)' pair from the hash
     table TABLE.  If TABLE does not hold an associated value for KEY,
     `#f' is returned.  Uses `equal?' for equality testing.

 - primitive: hashx-get-handle hash assoc table key
     This behaves the same way as the corresponding `-get-handle'
     function, but uses HASH as a hash function and ASSOC to compare
     keys.  `hash' must be a function that takes two arguments, a key
     to be hashed and a table size.  `assoc' must be an associator
     function, like `assoc', `assq' or `assv'.

 - primitive: hashq-create-handle! table key init
     This function looks up KEY in TABLE and returns its handle.  If
     KEY is not already present, a new handle is created which
     associates KEY with INIT.

 - primitive: hashv-create-handle! table key init
     This function looks up KEY in TABLE and returns its handle.  If
     KEY is not already present, a new handle is created which
     associates KEY with INIT.

 - primitive: hash-create-handle! table key init
     This function looks up KEY in TABLE and returns its handle.  If
     KEY is not already present, a new handle is created which
     associates KEY with INIT.

 - primitive: hashx-create-handle! hash assoc table key init
     This behaves the same way as the corresponding `-create-handle'
     function, but uses HASH as a hash function and ASSOC to compare
     keys.  `hash' must be a function that takes two arguments, a key
     to be hashed and a table size.  `assoc' must be an associator
     function, like `assoc', `assq' or `assv'.

 - primitive: hash-fold proc init table
     An iterator over hash-table elements.  Accumulates and returns a
     result by applying PROC successively.  The arguments to PROC are
     "(key value prior-result)" where key and value are successive
     pairs from the hash table TABLE, and prior-result is either INIT
     (for the first application of PROC) or the return value of the
     previous application of PROC.  For example, `(hash-fold acons '()
     tab)' will convert a hash table into an a-list of key-value pairs.

Hooks
=====

   A hook is basically a list of procedures to be called at well defined
points in time.  Hooks are used internally for several debugging
facilities, but they can be used in user code, too.

   Hooks are created with `make-hook', then procedures can be added to
a hook with `add-hook!' or removed with `remove-hook!' or
`reset-hook!'.  The procedures stored in a hook can be invoked with
`run-hook'.

Hook Examples
-------------

   Hook usage is shown by some examples in this section.  First, we will
define a hook of arity 2 -- that is, the procedures stored in the hook
will have to accept two arguments.

     (define hook (make-hook 2))
     hook
     => #<hook 2 40286c90>

   Now we are ready to add some procedures to the newly created hook
with `add-hook!'.  In the following example, two procedures are added,
which print different messages and do different things with their
arguments.  When the procedures have been added, we can invoke them
using `run-hook'.

     (add-hook! hook (lambda (x y)
                         (display "Foo: ")
                         (display (+ x y))
                         (newline)))
     (add-hook! hook (lambda (x y)
                         (display "Bar: ")
                         (display (* x y))
                         (newline)))
     (run-hook hook 3 4)
     -| Bar: 12
     -| Foo: 7

   Note that the procedures are called in reverse order than they were
added.  This can be changed by providing the optional third argument on
the second call to `add-hook!'.

     (add-hook! hook (lambda (x y)
                         (display "Foo: ")
                         (display (+ x y))
                         (newline)))
     (add-hook! hook (lambda (x y)
                         (display "Bar: ")
                         (display (* x y))
                         (newline))
                         #t)   ; <- Change here!
     (run-hook hook 3 4)
     -| Foo: 7
     -| Bar: 12

Hook Reference
--------------

   When a hook is created with `make-hook', you can supply the arity of
the procedures which can be added to the hook.  The arity defaults to
zero.  All procedures of a hook must have the same arity, and when the
procedures are invoked using `run-hook', the number of arguments must
match the arity of the procedures.

   The order in which procedures are added to a hook matters.  If the
third parameter to ADD-HOOK! is omitted or is equal to `#f', the
procedure is added in front of the procedures which might already be on
that hook, otherwise the procedure is added at the end.  The procedures
are always called from first to last when they are invoked via
`run-hook'.

   When calling `hook->list', the procedures in the resulting list are
in the same order as they would have been called by `run-hook'.

 - primitive: make-hook [n_args]
     Create a hook for storing procedure of arity N_ARGS.  N_ARGS
     defaults to zero.  The returned value is a hook object to be used
     with the other hook procedures.

 - primitive: hook? x
     Return `#t' if X is a hook, `#f' otherwise.

 - primitive: hook-empty? hook
     Return `#t' if HOOK is an empty hook, `#f' otherwise.

 - primitive: add-hook! hook proc [append_p]
     Add the procedure PROC to the hook HOOK. The procedure is added to
     the end if APPEND_P is true, otherwise it is added to the front.
     The return value of this procedure is not specified.

 - primitive: remove-hook! hook proc
     Remove the procedure PROC from the hook HOOK.  The return value of
     this procedure is not specified.

 - primitive: reset-hook! hook
     Remove all procedures from the hook HOOK.  The return value of
     this procedure is not specified.

 - primitive: run-hook hook . args
     Apply all procedures from the hook HOOK to the arguments ARGS.
     The order of the procedure application is first to last.  The
     return value of this procedure is not specified.

 - primitive: hook->list hook
     Convert the procedure list of HOOK to a list.

Other Core Guile Data Types
===========================

Procedures and Macros
*********************

Lambda: Basic Procedure Creation
================================

   A `lambda' expression evaluates to a procedure.  The environment
which is in effect when a `lambda' expression is evaluated is enclosed
in the newly created procedure, this is referred to as a "closure"
(see About Closure).

   When a procedure created by `lambda' is called with some actual
arguments, the environment enclosed in the procedure is extended by
binding the variables named in the formal argument list to new locations
and storing the actual arguments into these locations.  Then the body of
the `lambda' expression is evaluation sequentially.  The result of the
last expression in the procedure body is then the result of the
procedure invocation.

   The following examples will show how procedures can be created using
`lambda', and what you can do with these procedures.

     (lambda (x) (+ x x))       => a procedure
     ((lambda (x) (+ x x)) 4)   => 8

   The fact that the environment in effect when creating a procedure is
enclosed in the procedure is shown with this example:

     (define add4
       (let ((x 4))
         (lambda (y) (+ x y))))
     (add4 6)                   => 10

 - syntax: lambda formals body
     FORMALS should be a formal argument list as described in the
     following table.

    `(VARIABLE1 ...)'
          The procedure takes a fixed number of arguments; when the
          procedure is called, the arguments will be stored into the
          newly created location for the formal variables.

    `VARIABLE'
          The procedure takes any number of arguments; when the
          procedure is called, the sequence of actual arguments will
          converted into a list and stored into the newly created
          location for the formal variable.

    `(VARIABLE1 ... VARIABLEN . VARIABLEN+1)'
          If a space-delimited period precedes the last variable, then
          the procedure takes N or more variables where N is the number
          of formal arguments before the period.  There must be at
          least one argument before the period.  The first N actual
          arguments will be stored into the newly allocated locations
          for the first N formal arguments and the sequence of the
          remaining actual arguments is converted into a list and the
          stored into the location for the last formal argument.  If
          there are exactly N actual arguments, the empty list is
          stored into the location of the last formal argument.

     BODY is a sequence of Scheme expressions which are evaluated in
     order when the procedure is invoked.

Optional Arguments
==================

   Scheme procedures, as defined in R5RS, can wither handle a fixed
number of actual arguments, or a fixed number of actual arguments
followed by arbitrarily many additional arguments.  Writing procedures
of variable arity can be useful, but unfortunately, the syntactic means
for handling argument lists of varying length is a bit inconvenient.
It is possible to give names to the fixed number of argument, but the
remaining (optional) arguments can be only referenced as a list of
values (see Lambda).

   Guile comes with the module `(ice-9 optargs)', which makes using
optional arguments much more convenient.  In addition, this module
provides syntax for handling keywords in argument lists (see
Keywords).

   Before using any of the procedures or macros defined in this section,
you have to load the module `(ice-9 optargs)' with the statement:

     (use-modules (ice-9 optargs))

let-optional Reference
----------------------

   The syntax `let-optional' and `let-optional*' are for destructuring
rest argument lists and giving names to the various list elements.
`let-optional' binds all variables simultaneously, while
`let-optional*' binds them sequentially, consistent with `let' and
`let*' (see Local Bindings).

 - library syntax: let-optional rest-arg (binding ...) expr ...
 - library syntax: let-optional* rest-arg (binding ...) expr ...
     These two macros give you an optional argument interface that is
     very "Schemey" and introduces no fancy syntax. They are compatible
     with the scsh macros of the same name, but are slightly extended.
     Each of BINDING may be of one of the forms VAR or `(VAR
     DEFAULT-VALUE)'. REST-ARG should be the rest-argument of the
     procedures these are used from.  The items in REST-ARG are
     sequentially bound to the variable names are given. When REST-ARG
     runs out, the remaining vars are bound either to the default
     values or left unbound if no default value was specified. REST-ARG
     remains bound to whatever may have been left of REST-ARG.

     After binding the variables, the expressions EXPR ... are
     evaluated in order.

let-keywords Reference
----------------------

   `let-keywords' and `let-keywords*' are used for extracting values
from argument lists which use keywords instead of argument position for
binding local variables to argument values.

   `let-keywords' binds all variables simultaneously, while
`let-keywords*' binds them sequentially, consistent with `let' and
`let*' (see Local Bindings).

 - library syntax: let-keywords rest-arg allow-other-keys? (binding
          ...) expr ...
 - library syntax: let-keywords rest-arg allow-other-keys? (binding
          ...) expr ...
     These macros pick out keyword arguments from REST-ARG, but do not
     modify it.  This is consistent at least with Common Lisp, which
     duplicates keyword arguments in the rest argument. More
     explanation of what keyword arguments in a lambda list look like
     can be found below in the documentation for `lambda*'  (see
     lambda* Reference).  BINDINGs can have the same form as for
     `let-optional'. If ALLOW-OTHER-KEYS? is false, an error will be
     thrown if anything that looks like a keyword argument but does not
     match a known keyword parameter will result in an error.

     After binding the variables, the expressions EXPR ... are
     evaluated in order.

lambda* Reference
-----------------

   When using optional and keyword argument lists, using `lambda' for
creating procedures and using `let-optional' or `let-keywords' is a bit
lengthy.  Therefore, `lambda*' is provided, which combines the features
of those macros into a single convenient syntax.

   For quick reference, here is the syntax of the formal argument list
for `lambda*' (brackets are used to indicate grouping only):

     ext-param-list ::= [identifier]* [#:optional [ext-var-decl]+]?
       [#:key [ext-var-decl]+ [#:allow-other-keys]?]?
       [[#:rest identifier]|[. identifier]]?

     ext-var-decl ::= identifier | ( identifier expression )

   The characters `*', `+' and `?' are not to be taken literally; they
mean respectively, zero or more occurrences, one or more occurrences,
and one or zero occurrences.

 - library syntax: lambda* formals body
     `lambda*' creates a procedure that takes optional arguments. These
     are specified by putting them inside brackets at the end of the
     parameter list, but before any dotted rest argument. For example,

          (lambda* (a b #:optional c d . e) '())

     creates a procedure with fixed arguments A and B, optional
     arguments C and D, and rest argument E. If the optional arguments
     are omitted in a call, the variables for them are unbound in the
     procedure. This can be checked with the `bound?' macro (documented
     below).

     `lambda*' can also take keyword arguments. For example, a procedure
     defined like this:

          (lambda* (#:key xyzzy larch) '())

     can be called with any of the argument lists `(#:xyzzy 11)'
     `(#:larch 13)' `(#:larch 42 #:xyzzy 19)' `()'. Whichever arguments
     are given as keywords are bound to values.

     Optional and keyword arguments can also be given default values
     which they take on when they are not present in a call, by giving a
     two-item list in place of an optional argument, for example in:

          (lambda* (foo #:optional (bar 42) #:key (baz 73))
               (list foo bar baz))

     FOO is a fixed argument, BAR is an optional argument with default
     value 42, and baz is a keyword argument with default value 73.
     Default value expressions are not evaluated unless they are needed
     and until the procedure is called.

     `lambda*' also supports two more special parameter list keywords.

     `lambda*'-defined procedures now throw an error by default if a
     keyword other than one of those specified is found in the actual
     passed arguments. However, specifying `#:allow-other-keys'
     immediately after the keyword argument declarations restores the
     previous behavior of ignoring unknown keywords.  `lambda*' also now
     guarantees that if the same keyword is passed more than once, the
     last one passed is the one that takes effect. For example,

          ((lambda* (#:key (heads 0) (tails 0)) (display (list heads tails)))
              #:heads 37 #:tails 42 #:heads 99)

     would result in (99 47) being displayed.

     `#:rest' is also now provided as a synonym for the dotted syntax
     rest argument. The argument lists `(a . b)' and `(a #:rest b)' are
     equivalent in all respects to `lambda*'. This is provided for more
     similarity to DSSSL, MIT-Scheme and Kawa among others, as well as
     for refugees from other Lisp dialects.

 - library syntax: bound? variable
     Check if a variable is bound in the current environment.

     The procedure `defined?' doesn't quite cut it as it stands, since
     it only checks bindings in the top-level environment, not those in
     local scope only.

define* Reference
-----------------

   Just like `define' has a shorthand notation for defining procedures
(see Lambda Alternatives), `define*' is provided as an abbreviation
of the combination of `define' and `lambda*'.

   `define*-public' is the `lambda*' version of `define-public';
`defmacro*' and `defmacro*-public' exist for defining macros with the
improved argument list handling possibilities.  The `-public' versions
not only define the procedures/macros, but also export them from the
current module.

 - library syntax: define* formals body
 - library syntax: define*-public formals body
     `define*' and `define*-public' support optional arguments with a
     similar syntax to `lambda*'. They also support arbitrary-depth
     currying, just like Guile's define. Some examples:

          (define* (x y #:optional a (z 3) #:key w . u)
             (display (list y z u)))
     defines a procedure `x' with a fixed argument Y, an optional
     argument A, another optional argument Z with default value 3, a
     keyword argument W, and a rest argument U.

          (define-public* ((foo #:optional bar) #:optional baz) '())

     This illustrates currying. A procedure `foo' is defined, which,
     when called with an optional argument BAR, returns a procedure
     that takes an optional argument BAZ.

     Of course, `define*[-public]' also supports `#:rest' and
     `#:allow-other-keys' in the same way as `lambda*'.

 - library syntax: defmacro* name formals body
 - library syntax: defmacro*-public name formals body
     These are just like `defmacro' and `defmacro-public' except that
     they take `lambda*'-style extended parameter lists, where
     `#:optional', `#:key', `#:allow-other-keys' and `#:rest' are
     allowed with the usual semantics. Here is an example of a macro
     with an optional argument:

          (defmacro* transmorgify (a #:optional b)
              (a 1))

Procedure Properties and Meta-information
=========================================

   Procedures always have attached the environment in which they were
created and information about how to apply them to actual arguments.  In
addition to that, properties and meta-information can be stored with
procedures.  The procedures in this section can be used to test whether
a given procedure satisfies a condition; and to access and set a
procedure's property.

   The first group of procedures are predicates to test whether a Scheme
object is a procedure, or a special procedure, respectively.
`procedure?' is the most general predicates, it returns `#t' for any
kind of procedure.  `closure?' does not return `#t' for primitive
procedures, and `thunk?' only returns `#t' for procedures which do not
accept any arguments.

 - primitive: procedure? obj
     Return `#t' if OBJ is a procedure.

 - primitive: closure? obj
     Return `#t' if OBJ is a closure.

 - primitive: thunk? obj
     Return `#t' if OBJ is a thunk.

   Procedure properties are general properties to be attached to
procedures.  These can be the name of a procedure or other relevant
information, such as debug hints.

 - primitive: procedure-properties proc
     Return OBJ's property list.

 - primitive: procedure-property p k
     Return the property of OBJ with name KEY.

 - primitive: set-procedure-properties! proc new_val
     Set OBJ's property list to ALIST.

 - primitive: set-procedure-property! p k v
     In OBJ's property list, set the property named KEY to VALUE.

   Documentation for a procedure can be accessed with the procedure
`procedure-documentation'.

 - primitive: procedure-documentation proc
     Return the documentation string associated with `proc'.  By
     convention, if a procedure contains more than one expression and
     the first expression is a string constant, that string is assumed
     to contain documentation for that procedure.

   Source properties are properties which are related to the source
code of a procedure, such as the line and column numbers, the file name
etc.

 - primitive: set-source-properties! obj plist
     Install the association list PLIST as the source property list for
     OBJ.

 - primitive: set-source-property! obj key datum
     Set the source property of object OBJ, which is specified by KEY
     to DATUM.  Normally, the key will be a symbol.

 - primitive: source-properties obj
     Return the source property association list of OBJ.

 - primitive: source-property obj key
     Return the source property specified by KEY from OBJ's source
     property list.

Procedures with Setters
=======================

   A "procedure with setter" is a special kind of procedure which
normally behaves like any accessor procedure, that is a procedure which
accesses a data structure.  The difference is that this kind of
procedure has a so-called "setter" attached, which is a procedure for
storing something into a data structure.

   Procedures with setters are treated specially when the procedure
appears in the special form `set!' (REFFIXME).  How it works is best
shown by example.

   Suppose we have a procedure called `foo-ref', which accepts two
arguments, a value of type `foo' and an integer.  The procedure returns
the value stored at the given index in the `foo' object.  Let `f' be a
variable containing such a `foo' data structure.(1)

     (foo-ref f 0)       => bar
     (foo-ref f 1)       => braz

   Also suppose that a corresponding setter procedure called `foo-set!'
does exist.

     (foo-set! f 0 'bla)
     (foo-ref f 0)       => bla

   Now we could create a new procedure called `foo', which is a
procedure with setter, by calling `make-procedure-with-setter' with the
accessor and setter procedures `foo-ref' and `foo-set!'.  Let us call
this new procedure `foo'.

     (define foo (make-procedure-with-setter foo-ref foo-set!))

   `foo' can from now an be used to either read from the data structure
stored in `f', or to write into the structure.

     (set! (foo f 0) 'dum)
     (foo f 0)          => dum

 - primitive: make-procedure-with-setter procedure setter
     Create a new procedure which behaves like PROCEDURE, but with the
     associated setter SETTER.

 - primitive: procedure-with-setter? obj
     Return `#t' if OBJ is a procedure with an associated setter
     procedure.

 - primitive: procedure proc
     Return the procedure of PROC, which must be either a procedure
     with setter, or an operator struct.

 - primitive: setter proc
     Return the setter of PROC, which must be either a procedure with
     setter or an operator struct.

   ---------- Footnotes ----------

   (1) Working definitions would be:
     (define foo-ref vector-ref)
     (define foo-set! vector-set!)
     (define f (make-vector 2 #f))

Lisp Style Macro Definitions
============================

   Macros are objects which cause the expression that they appear in to
be transformed in some way _before_ being evaluated.  In expressions
that are intended for macro transformation, the identifier that names
the relevant macro must appear as the first element, like this:

     (MACRO-NAME MACRO-ARGS ...)

   In Lisp-like languages, the traditional way to define macros is very
similar to procedure definitions.  The key differences are that the
macro definition body should return a list that describes the
transformed expression, and that the definition is marked as a macro
definition (rather than a procedure definition) by the use of a
different definition keyword: in Lisp, `defmacro' rather than `defun',
and in Scheme, `define-macro' rather than `define'.

   Guile supports this style of macro definition using both `defmacro'
and `define-macro'.  The only difference between them is how the macro
name and arguments are grouped together in the definition:

     (defmacro NAME (ARGS ...) BODY ...)

is the same as

     (define-macro (NAME ARGS ...) BODY ...)

The difference is analogous to the corresponding difference between
Lisp's `defun' and Scheme's `define'.

   `false-if-exception', from the `boot-9.scm' file in the Guile
distribution, is a good example of macro definition using `defmacro':

     (defmacro false-if-exception (expr)
       `(catch #t
               (lambda () ,expr)
               (lambda args #f)))

The effect of this definition is that expressions beginning with the
identifier `false-if-exception' are automatically transformed into a
`catch' expression following the macro definition specification.  For
example:

     (false-if-exception (open-input-file "may-not-exist"))
     ==
     (catch #t
            (lambda () (open-input-file "may-not-exist"))
            (lambda args #f))

The R5RS `syntax-rules' System
==============================

   R5RS defines an alternative system for macro and syntax
transformations using the keywords `define-syntax', `let-syntax',
`letrec-syntax' and `syntax-rules'.

   The main difference between the R5RS system and the traditional
macros of the previous section is how the transformation is specified.
In R5RS, rather than permitting a macro definition to return an
arbitrary expression, the transformation is specified in a pattern
language that

   * does not require complicated quoting and extraction of components
     of the source expression using `caddr' etc.

   * is designed such that the bindings associated with identifiers in
     the transformed expression are well defined, and such that it is
     impossible for the transformed expression to construct new
     identifiers.

The last point is commonly referred to as being "hygienic": the R5RS
`syntax-case' system provides "hygienic macros".

   For example, the R5RS pattern language for the `false-if-exception'
example of the previous section looks like this:

     (syntax-rules ()
       ((_ expr)
        (catch #t
               (lambda () expr)
               (lambda args #f))))

   In Guile, the `syntax-rules' system is provided by the `(ice-9
syncase)' module.  To make these facilities available in your code,
include the expression `(use-modules (ice-9 syncase))' or `(use-syntax
(ice-9 syncase))' (see Using Guile Modules) before the first usage
of `define-syntax' etc.  If you are writing a Scheme module, you can
alternatively use one of the keywords `#:use-module' and `#:use-syntax'
in your `define-module' declaration (see Creating Guile Modules).

The `syntax-rules' Pattern Language
-----------------------------------

Top Level Syntax Definitions
----------------------------

   define-syntax:  The gist is

   (define-syntax <keyword> <transformer-spec>)

   makes the <keyword> into a macro so that

   (<keyword> ...)

   expands at _compile_ or _read_ time (i.e. before any evaluation
begins) into some expression that is given by the <transformer-spec>.

Local Syntax Definitions
------------------------

Support for the `syntax-case' System
====================================

Internal Representation of Macros and Syntax
============================================

   Internally, Guile uses three different flavors of macros.  The three
flavors are called "acro" (or "syntax"), "macro" and "mmacro".

   Given the expression

     (foo ...)

with `foo' being some flavor of macro, one of the following things will
happen when the expression is evaluated.

   * When `foo' has been defined to be an "acro", the procedure used in
     the acro definition of `foo' is passed the whole expression and
     the current lexical environment, and whatever that procedure
     returns is the value of evaluating the expression.  You can think
     of this a procedure that receives its argument as an unevaluated
     expression.

   * When `foo' has been defined to be a "macro", the procedure used in
     the macro definition of `foo' is passed the whole expression and
     the current lexical environment, and whatever that procedure
     returns is evaluated again.  That is, the procedure should return
     a valid Scheme expression.

   * When `foo' has been defined to be a "mmacro", the procedure used
     in the mmacro definition of `foo' is passed the whole expression
     and the current lexical environment, and whatever that procedure
     returns replaces the original expression.  Evaluation then starts
     over from the new expression that has just been returned.

   The key difference between a "macro" and a "mmacro" is that the
expression returned by a "mmacro" procedure is remembered (or
"memoized") so that the expansion does not need to be done again next
time the containing code is evaluated.

   The primitives `procedure->syntax', `procedure->macro' and
`procedure->memoizing-macro' are used to construct acros, macros and
mmacros respectively.  However, if you do not have a very special
reason to use one of these primitives, you should avoid them: they are
very specific to Guile's current implementation and therefore likely to
change.  Use `defmacro', `define-macro' (see Macros) or
`define-syntax' (see Syntax Rules) instead.  (In low level terms,
`defmacro', `define-macro' and `define-syntax' are all implemented as
mmacros.)

 - primitive: procedure->syntax code
     Return a macro which, when a symbol defined to this value appears
     as the first symbol in an expression, returns the result of
     applying CODE to the expression and the environment.

 - primitive: procedure->macro code
     Return a macro which, when a symbol defined to this value appears
     as the first symbol in an expression, evaluates the result of
     applying CODE to the expression and the environment.  For example:

          (define trace
            (procedure->macro
              (lambda (x env)
                `(set! ,(cadr x) (tracef ,(cadr x) ',(cadr x))))))

          (trace foo)
          ==
          (set! foo (tracef foo 'foo)).

 - primitive: procedure->memoizing-macro code
     Return a macro which, when a symbol defined to this value appears
     as the first symbol in an expression, evaluates the result of
     applying CODE to the expression and the environment.
     `procedure->memoizing-macro' is the same as `procedure->macro',
     except that the expression returned by CODE replaces the original
     macro expression in the memoized form of the containing code.

   In the following primitives, "acro" flavor macros are referred to as
"syntax transformers".

 - primitive: macro? obj
     Return `#t' if OBJ is a regular macro, a memoizing macro or a
     syntax transformer.

 - primitive: macro-type m
     Return one of the symbols `syntax', `macro' or `macro!', depending
     on whether M is a syntax transformer, a regular macro, or a
     memoizing macro, respectively.  If M is not a macro, `#f' is
     returned.

 - primitive: macro-name m
     Return the name of the macro M.

 - primitive: macro-transformer m
     Return the transformer of the macro M.

 - primitive: cons-source xorig x y
     Create and return a new pair whose car and cdr are X and Y.  Any
     source properties associated with XORIG are also associated with
     the new pair.

General Utility Functions
*************************

   This chapter contains information about procedures which are not
cleanly tied to a specific data type.  Because of their wide range of
applications, they are collected in a "utlity" chapter.